FishMarket 1.0/FishMarket v1.0.iso/fishies/326-350/disk_348/dissecretary/dissecretary.doc

Text File | 1992-05-06 | 28KB | 509 lines

Set your editor's TAB width to 3

**************************************************************************
disSecretary            version #:  Wanda

    1).  Introduction
    2).  Cabinets and Folders
    3).  Protect and Program modes
    4).  Creating/Editing a Data Item
    5).  Moving from Item to Item
    6).  Inserting a new Item
    7).  Deleting an existing Item
    8).  Editor Commands
    9).  Saving Data Files
    10). Loading Data Files
    11). Printing Data Files
    12). Importing/Exporting Items
    13). Clipping/Copying text to Items
    14). Finding strings
    15). Changing Cabinet and Folder names
    16). Saving and Loading Cabinet/Folder names
    17). Searching Cabinets/Folders
    18). Any/All Folders
    19). WorkBench/CLI operation
    20). Support Files
    21). Updates, Bug Reports, etc

***************************************************************************
1). Introduction

    disSecretary is a program which allows you to organize data items (com-
prised of ascii text) into a "file cabinet" environment.  Such applications
include:

    1). Maintaining a disk catalog
    2). Keeping track of club memberships (especially with SIGs)
    3). Organizing checks, bills, and receipts
    4). Cataloging compact disc, magazine, and video tape collections

It was written to be flexible enough for a variety of applications and easy to
use, but also to be small and fast.  Written entirely in 68000 assembly, and
using the dissidents custom libraries, it is able to achieve these goals.  The
total size of the program is about 37K, and all but 10K of this is the
dissidents shared libraries.  This means that disSecretary will multi-task
extremely well with itself, and any other dissidents products.
    This program is completely self-contained in that you use it to create
data files, edit data files, and search through data files.
    For the creation and editing of data files, it contains a built in
text editor virtually identical to the dissidents text editor, disED.  Most
all of the commands are the same, and include the ability to import ascii
text, enter and display control and printer codes, cursor to any text using
the mouse or cursor keys, block cut/paste, word wrap, overstrike, margins,
auto-indent, programmable macro keys, search/exchange, etc.  disSecretary
even uses the same configuration files as disED.  If you have not yet
read the documentation for disED, you should do so now as this document will
not duplicate that information.  Any differences in the text entry features
between these two programs will be noted in this document.  Otherwise, anything
that you can do in our text editor, you can do in disSecretary.
    In edition to the text entry features, there are gadgets which allow
you to choose where a given piece of information is stored.
    For examining data files, the gadgets are used to determine where to
look for information, and to specify what kind of information to look for.
    In order to run disSecretary, the following libraries must be copied
to the LIBS: dir of your boot disk.

    text_ed.library
    dised.library
    requester.library
    color.library  (if you want to change the window colors)

Workbench users simply click on the "Click Me First" gadget on the enclosed
disk.  This invokes a program which copies the necessary libraries for you.
CLI users must CD to the directory containing InstallLibs and run it.


**************************************************************************
2). Cabinets and Folders

    There are 8 file "Cabinets" into which you can put pieces of information.
Inside each cabinet is 8 "Folders".  A given piece of information can be
placed in only one cabinet, but in as many of the Folders as desired within
that cabinet.
    disSecretary displays the names of all eight Cabinets in 8 boxes on the
lower left corner of the window.  Any unnamed Cabinets have empty boxes.
The boxes are arranged in columns of four.  Think of each box as a metal
file cabinet.  For example, if we have 6 Cabinets named "Hardware", "SoftWare",
"Books", "Magazines", "Disks", and "Parts", the 8 boxes would look like this:

 -------------  ------------
 | HardWare  |  | Disks    |
 =============  ============
 | SoftWare  |  | Parts    |
 =============  ============
 | Books     |  |          |
 =============  ============
 | Magazines |  |          |
 -------------  ------------

    Note that the last two Cabinets (boxes) are unnamed and therefore left
blank.  Only 1 Cabinet can be selected at a time. You select a Cabinet by
positioning the mouse over the desired box, and clicking the left button.
The selected Cabinet's name will be highlighted (a different color than the
other 7 boxes).
    On the lower right-hand corner of the window are 8 boxes containing the
names of the 8 Folders INSIDE THE SELECTED CABINET.  For example, inside
the "Hardware" cabinet could be five Folders called "Computers", "Monitors",
"Disk Drives", "Midi", and "Video".  If you selected the "Hardware" cabinet,
the Folder names would appear as so:

                                       ---------------  --------------
                                       | Computers   |  | Video      |
                                       ===============  ==============
                                       | Monitors    |  |            |
                                       ===============  ==============
                                       | Disk Drives |  |            |
                                       ===============  ==============
                                       | Midi        |  |            |
                                       ===============  ==============


    Note that "Video" starts in the second column of the Folder names
because it is the fifth Folder.
    If you were to select the "Books" cabinet, the 8 Folders would change
to the names of the Folders inside of that cabinet, and the box named "Books"
would be highlighted.
    You can select as many Folders as you wish. When a Folder is selected,
it is highlighted (orange background using standard WorkBench colors). If you
click on a selected Folder, it will no longer be selected, and its color will
revert back to the same color as the window.


****************************************************************************
3). Protect and Program modes

    When disSecretary firsts starts, it is in PROTECT mode.  This prevents
you from altering any previous data items (or changing their attributes), or
adding any new items to the data file.  There is a box inbetween the Cabinet
and Folder names labeled "Protect".  If you click once on this box, it will
change to "Program" and will be highlighted.  In this mode, you can now edit
data items or create new ones.
    Protect mode is used when you want to examine a data file (i.e. search for
items in certain Cabinets and Folders).  Program mode is used when you want to
change a data file (i.e. edit or delete an item, or create a new item).


*****************************************************************************
4). Creating/Editing a Data Item

    The top half of the window (above the Cabinet and Folder names) is where
you enter whatever text you wish for one data item. There is an orange
cursor showing where to enter text.  As soon as you type on the keyboard, your
input appears in the top half of the window.  As you fill up this portion of
the window, text will start scrolling.  Just like with disED, you can use the
mouse or cursor keys to reposition the cursor, and the DEL and BACKSPACE to
remove characters.  Text editing commands are entered by holding down the
CTRL key, and pressing another key.  Consult the disED doc for available
commands and how to use them.  Remember that this is a real text editor.  When
you wish to start a new line, press RETURN.
    Let's create a data item.  Enter the following 2 lines of text as our data
item:

This is Item #1.
It is stored in Cabinet 1,  Folders 1 and 2.

    Now, make sure that Cabinet 1 is highlighted by clicking on its box.
Initially, when disSecretary is first run, all Folders are selected (i.e. an
orange background).  Make sure that Folder boxes number 1 and 2 are selected.
As you click on the box, it is highlighted to indicate that it is selected.  If
you click on the same box again, it will be un-highlighted indicating that this
Folder is no longer selected.  Make sure that all Folders except #1 and #2 are
NOT selected (i.e. blue background).  We are now ready to "file" our data item
in Folders #1 and #2 inside of Cabinet #1.  Locate a box inbetween the Cabinets
and Folders labeled "File", and click on this box.  You have now stored the
data item (i.e. the entered text).
    If you decide to change the data item before moving on, simply use the
mouse or cursor keys to go to the text that you wish to change, and use the
DEL, BACKSPACE, or cut/paste commands to alter the text.  You also might choose
to store this item in different Folders or another Cabinet.  Simply select the
desired boxes.  After making your changes, click on "File" to resave this data
item with the new changes.
    Items are stored in the order that they are entered (unless you move
to another place in the data file).


*****************************************************************************
5). Moving from Item to Item

    Inbetween the Cabinet and Folders are four arrow gadgets.  There is
an up arrow, a left arrow, a right arrow, and a down arrow.  The gadgets look
something like this:

          up    left  right  down

           ^     <<    >>     v

    When in PROGRAM mode, the right arrow advances to the next item in the
data file, and the left arrow moves back to the previous item in the data file.
When there are no more "next" items and you select the right arrow, it is
highlighted.  When there are no more "previous" items and you select the left
arrow, it is highlighted.  The up arrow moves to before the first item in the
data file (the head of the file), and the down arrow moves to after the last
item (the tail).  For example, if you are in the middle of the data file and
wish to go to the first entered item, click on the up arrow.  Any visible text
should disappear since we are now before the first data item.  Click on the
right arrow and the text for the first item appears.  Also, the Cabinet and
Folders in which the item is stored are highlighted.
    Now, click on the right arrow again.  The text for the next item is now
displayed and its Cabinet and Folders are highlighted.  Since we haven't yet
entered a second item, the text area should be blank and the right arrow should
turn red to indicate that we are at the tail of the file.  Let's enter the
following 2 lines.

This is Item #2.
It is stored in Cabinet 4,  Folders 4, 5, and 6.

Click on the box for Cabinet 4, and select (highlight) Folders 4, 5, and 6.
Make sure that all other Folders are not selected.  Then click on the "File"
box to store this item.
    Now, when you click on the left arrow to move back to the previous
item, you should see its text, and Cabinet 1, Folders 1 and 2 are highlighted.
Press the right arrow to return to the second item.  Understand?
    If you press the right arrow again, you will be past the last item, and
can enter a third data item.  Take the time to add a few items and click on the
arrows to get a feel for how to create items, and move from item to item.
    You can also go to the head of the data file by clicking on the up arrow,
and create a new item here. This new item will then become the first in the
data file.

NOTE: You cannot move from one item to the next when in PROTECT mode because
the left and right arrows control search direction instead.  See Section 17.


*****************************************************************************
6). Inserting a new Item

    When you move to the head or tail of the data file (by clicking the up or
down arrows respectively), disSecretary automatically clears the text area.
Also, if you press the left or right arrow and move off into the head or tail
of the data file (i.e. the arrow turns red), the text area is automatically
cleared.  At this point, you can enter a new data item.  Simply, enter the
text, make your Cabinet/Folder selections, and "File" it.  In this way, it is
very easy to append (or prepend) several items to a data file.  On the other
hand, you may wish to insert a new item somewhere in the middle of the data
file.  Note that as you press the left or right arrows while not at the "ends"
of the data file, the text area doesn't clear.  Rather, you always move to the
next/previous item.  disSecretary assumes that you want to edit existing items
and is attempting to streamline the process.  Do not clear the text area using
the Clear menu, or manually delete or clip out the characters.  You are editing
an existing Data Item, not creating a new one.  (Note that until you actually
click on the "File" gadget, the edits are temporary).  In order to insert a new
item inbetween two others, you must click on the "New" gadget (above the File
box).  This will clear the display in preparation of a new item.  The new item
will be inserted before the previously displayed item.  Note that if you never
enter any text, no item will be stored when you click on "File".


*****************************************************************************
7). Deleting an existing Item

    First, check that you are in PROGRAM mode.  Next, make sure that the item
you want to delete is being displayed.  Finally, select "Clear Item" from the
project menu.  (Do not select "Clear Data File" as this will erase all data
items.)  The data item will be deleted, and you will automatically move to the
next item in the data file.
    Note that if you were to clip out all of an item's text (i.e. a blank text
area) and clicked on "File", this would delete that item as well. You cannot
save a blank item in a data file.


****************************************************************************
8). Editor Commands

    All editor commands affect only the currently displayed text (item). For
example, the INSERT CLIP inserts text into the current item.  The SEARCH and
EXCHANGE commands (i.e CTRL-e), also affect only the displayed text. Remember
that those edits to a Data Item don't become permanent until you click on
"File".  Note that if you make changes and attempt to move to another item
without fileing it first, disSecretary will prompt you to change your mind.
    Unlike disED, disSecretary does not allow EXTRA WIDE spacing, or allow
you to change any flags using the '+' and '-' commands.  For this reason,
macros using these commands will not work the same in disSecretary.  Otherwise,
all other command invocations work the same.  See the disED document.


*****************************************************************************
9). Saving Data Files

    You save your Data File by either invoking SAVE or SAVE AS (Data File)
from the Project menu.  SAVE will simply save your data file using the original
(or last saved) name.  SAVE AS will bring up the FileIO requester to allow you
to make your selection.  The requester has many features which you can custom-
ize (and save in the config file).  See the FileIO documentation.
    Don't get the SAVE menu mixed up with the "File" box.  The File box
only saves the edits to an existing item or a new item IN MEMORY.  There is no
disk access at all when you create/edit/search a data file.  It is loaded
entirely into memory, and must be saved via the Project menu after any changes
are made.  While a program that only loads partial files from disk may be less
memory intensive for large data files, it is slower. Also, the constant
thrashing of drive heads as repeated searches are made is not good. disSecre-
tary is designed to work well in computers with even modest amounts of memory.


*****************************************************************************
10). Loading Data Files

    You can load a new data file by invoking the LOAD (Data File) from the
Project menu.  The FileIO requester allows you to make your selection.  Any
previously loaded Data File is overwritten. When disSecretary is first started,
it allocates a portion of your free memory for loading data files.  If you
intend to multitask with disSecretary, run your other programs first.  If,
when loading a large file, you see the message "File truncated. Edit buffer
must be resized", this means that disSecretary cannot allocate enough memory
for the file.  Exit disSecretary, close down other applications to free memory,
and then try again.  Although you could search through a truncated file, never
save it since data could be lost.


*****************************************************************************
11). Printing Data Files

    This is not implemented yet, and future upgrades may only be issued
to folks who take me up on the ShareWare offer.


*****************************************************************************
12). Importing/Exporting Items

    You can export or import text into disSecretary by the SAVE AS ITEM and
LOAD ITEM menus.  For example, you may wish to save the currently displayed
item only.  Invoke SAVE AS ITEM.  Alternately, you may wish to create a new
item by loading in some text instead of typing it in by hand.  Clear the text
area as described in section 6, and invoke LOAD ITEM.  You can load over an
existing Item (i.e. while its text is displayed in the window), and resave
with the "File" box, thus updating the item.


*****************************************************************************
13). Clipping/Copying text to Items

    Besides being able to cut/paste text within a Item, you can also clip
or copy text between items using the CTRL-x or CTRL-y commands.  Clip or copy
the desired text.  Then move to another Item using the arrow boxes, or create
a new item with the New box.  Paste the text with the CTRL-i command.


******************************************************************************
14). Finding Strings

    As mentioned, the SEARCH commands (CTRL-f and CTRL-b) work only on the
currently displayed item (text).  Above the File box, is a box labeled "Find".
This allows you to search the entire data file for a particular string.  You
enter the string just as with the editor search commands.  A search for the
string is begun AT THE ITEM AFTER THE CURRENTLY DISPLAYED ITEM.  This is a
forward search to the end of the file, case in-sensitive.  If an item is found
which contains the string, that item is displayed.  If no item is found, then
the message "Not Found" appears in the title bar.
    If you wish to search the entire data file for a string, you should
move to the head of the file by clicking the up arrow box.  Initiate the FIND.
The first matching item will be displayed.  If you invoke FIND again, the next
matching item will be displayed, etc.
    The FIND box searches ALL items, regardless of what the selected Cabinet
and Folder settings are, or whether the current mode is PROTECT or PROGRAM.


******************************************************************************
15). Changing Cabinet and Folder names

    You can change a Cabinet or Folder name by invoking the SetUp menu's
Change Key.  You will be prompted to click on the box whose name you wish to
change, and then prompted to type in a new name.  Remember that the ESC key
always lets you bail out of having to enter input.  Let's say that we wish to
change the first Folder in Cabinet #2.  First, select Cabinet #2 to display
its Folder names in the Folder boxes.  Invoke Change Key.  Click on the first
Folder box.  After you enter the new name, it will be displayed in the box.


******************************************************************************
16). Saving and Loading Cabinet/Folder names


    You should save the names after changing them.  The Cabinet/Folder names
are saved in a file separate from the data file.  In this way, you can use 1
Cabinet/Folder "Key" file for many data files.  Invoke the Project menu's SAVE
AS Keys.  The default name for the file is CabinetKeys.  When disSecretary
starts up, it auto-loads any file in the current directory with this name.
Alternately, you may elect to save with a different name. In order to use that
key file, you must load it using the Project menu's LOAD Keys.  Loading a new
key file doesn't affect the data file at all.


*****************************************************************************
17). Searching Cabinets/Folders

    You must switch to PROTECT mode to search for Items in a data file. This
changes the way in which the left and right arrow boxes, as well as the
Cabinet/Folder settings work.  In PROTECT mode, the Cabinet and Folder names
no longer alter to show the settings of the currently displayed Item.  Rather,
you set the boxes to determine what Cabinet and Folders you wish to peruse.
For example, let's assume that you have a Cabinet named "Games".  Inside this
Cabinet are Folders named "Cards", "Text Adventure", "Video", and  "X-rated".
You wish to peruse a data file of all items that were stored in the "Games"
Cabinet, and in the "Cards" or "Video" Folders.  Click on the "Games" Cabinet's
box, and then highlight the "Video" and "Cards" Folder boxes.  Now, when you
click on the right arrow, it will find the next item AFTER THE CURRENT ITEM
that was filed in this place.  Note that in order for an item to match, it must
be in the "Games" Cabinet.  It could be in either the "Cards" or "Video"
Folders, or even in both.  But if it is not in the "Games" cabinet or in either
of those 2 Folders, it will be skipped.  As you continue to click the right
arrow, you will move forward to the next matching Item.  When no more matches
are found, the message "Not Found" appears in the title bar.
    The left arrow searches BACKWARDS FROM THE CURRENT ITEM.  Note that if
you wish to start searching from the first or last item in the data file, you
should first move to the head or tail with the up or down arrows.  Then use
the left/right arrow boxes to move through the file.
    When a matching item is found, the boxes are not changed to reflect the
true attributes of the item.  For example, an Item in the "Games" Cabinet that
was filed in the "Video" and "X-rated" Folders would match our search.  But
when it was displayed, the highlighted Folders would remain "Video" and
"Cards".  If you switch back to PROGRAM mode, the boxes "Video" and "X-rated"
would be highlighted, and "Cards" would not.


*****************************************************************************
18). Any/All Folders

    To the left of the FIND gadget is the Any/All gadget.  Initially, this
gadget reads "Any".  If you click on the word "Any", it will change to "All",
and vice versa.  This gadget affects the way in which the Folders are matched
when searching through a data file.
    If "Any", an item which is in any one or more of the highlighted Folders
will match a search.  For example, you may have a "Programs" cabinet, and in
it, two Folders, "C" and "Assembly".  You have selected this cabinet and both
Folders.  If you have the Any gadget set, then you would match all items that
were filed in either the "C" or "Assembly" Folders, or both Folders.
    If "All", an item must be in ALL of the highlighted Folders to match, not
just any of the Folders.  For the previous example, you would only match items
that were in both the "C" and "Assembly" Folders.
    "Any" is useful if you are doing a general search (i.e. you want to find
something that may be in any of several Folders).  "All" is useful for a
specific search (i.e. you want an item that exactly matches your Folder speci-
fications).


*****************************************************************************
19). WorkBench/CLI Operation

    From the WorkBench, there are two ways to start disSecretary.  You can
click on the disSecretary icon, in which case the program will be invoked
without any data file.  Any key file named "CabinetKeys" in the same drawer as
the program will automatically be loaded.  Otherwise, the FileIO requester will
prompt you to choose the key file to load.  If you CANCEL, the Cabinet and
Folders will have blank names.  Any config will be loaded as described in
disED's doc.
    Alternately, you can click on the icon for any data file made with
disSecretary.  The program will automatically be invoked.  The data file will
be loaded along with any key file named "CabinetKeys" in the same drawer as
the data file.
    From the CLI, disSecretary takes one optional argument; the name of the
data file to load.  The key file loaded is always the file named "CabinetKeys"
in the current directory.  If no such file exists, the FileIO requester prompts
for the key filename to load.  If you CANCEL, the Cabinet and Folder names are
blank.


*****************************************************************************
20). Support Files

    Since disSecretary uses the same config file and macro format as disED,
any of those support files for the editor can be loaded and will work.  The
exception is any macro that uses the '+' or '-' commands.  Also, since the
menus between programs are slightly different, some macros which reference
menus may need to be changed.
    There is a default key file (i.e. CabinetKeys) which is just to help
you understand the operation of the Cabinet/Folder boxes.
    There is a data file for the Fred Fish catalog. It is called FishFile. The
key file for it is FishKeys.  You should load FishKeys (via LOAD Keys), and
FishFile (via LOAD Data File).  If you delete the original CabinetKeys, and
rename FishKeys to CabinetKeys, disSecretary will automatically load it.


******************************************************************************
21). Updates, Bug Reports, etc

    All bug reports should be sent to the address below. Don't just grumble
to yourself if something goes wrong.  Let me know so that I can correct it.
    Updates will include the printing feature, perhaps a GOTO ITEM NUMBER
if there appears to be interest in this feature (I couldn't think of a good
use since you can search by location or text matching already), and any other
suggestions from gracious users.
    dissidents has to date made several useful contributions to the public
domain software library.  This program is going out as ShareWare because,
after all, I'd like to think that my effort is worth something.  If you're one
of those bloated, pie-eating hiefers who gets his software for "free", go ahead
and use the program, but at least don't start whining when the market for Amiga
software (and hardware) dries up because no one could make any money.  I don't
know any Amiga programmer who is collecting royalties as he lounges in a
sparkling champagne bath, leisurely puffing on a fat Cuban cigar and pondering
his next multi-million dollar coporate acquisition, while his pampered pet
poodle, Tourielle, horses down fresh caviar from a 14-carat gold doggie dish
with his name handsomely engraved on the side in delicate, handcarved charac-
ters, and a very proper, elderly English butler attentively stands nearby with
a silk handkerchief waiting for any indelicate situation to occur should
Tourielle decide that it is beneath his dignity to rush outdoors and lift his
leg against a fire hydrant.  OK, maybe R.J. Mical, but the rest of us...
    Suggested donation for the real versions of disED and disSecretary,
plus a general feeling that you have somehow restored my faith in the kindness
of strangers, and a promise from me not to sicken you with further, obviously
ingratiating and insincere comments: 25 U.S. dollars.